

package com.hazelcast.jet;

import com.hazelcast.jet.core.JobStatus;

import java.util.UUID;

/**
 * Invoked upon job status change. <ol>
 * <li> This listener observes that the status is transitioned to {@link
 * JobStatus#SUSPENDED SUSPENDED}/{@link JobStatus#FAILED FAILED} upon job
 * {@linkplain Job#suspend suspension}/{@linkplain Job#cancel termination},
 * {@link JobStatus#NOT_RUNNING NOT_RUNNING} upon job {@linkplain
 * Job#resume resume}/{@linkplain Job#restart restart}, and {@link
 * JobStatus#SUSPENDED_EXPORTING_SNAPSHOT SUSPENDED_EXPORTING_SNAPSHOT}
 * upon {@linkplain Job#exportSnapshot exporting snapshot}, all of which
 * are reported as user-initiated. Other transitions, such as from {@link
 * JobStatus#NOT_RUNNING NOT_RUNNING} to {@link JobStatus#STARTING
 * STARTING} or from {@link JobStatus#STARTING STARTING} to {@link
 * JobStatus#RUNNING RUNNING}, are not reported as user-initiated.
 * <li> This listener is not notified for {@link JobStatus#COMPLETING
 * COMPLETING} status and observes that the status is transitioned from
 * {@link JobStatus#RUNNING RUNNING} to {@link JobStatus#FAILED FAILED}
 * upon job {@linkplain Job#cancel termination}.
 * <li> This listener is automatically deregistered after a {@linkplain
 * JobStatus#isTerminal terminal event}. </ol>
 *
 * @see Job#addStatusListener(JobStatusListener)
 * @see Job#removeStatusListener(UUID)
 * @since 5.3
 */
@FunctionalInterface
public interface JobStatusListener {
    /**
     * Invoked upon job status change. <ol>
     * <li> This listener observes that the status is transitioned to {@link
     * JobStatus#SUSPENDED SUSPENDED}/{@link JobStatus#FAILED FAILED} upon job
     * {@linkplain Job#suspend suspension}/{@linkplain Job#cancel termination},
     * {@link JobStatus#NOT_RUNNING NOT_RUNNING} upon job {@linkplain
     * Job#resume resume}/{@linkplain Job#restart restart}, and {@link
     * JobStatus#SUSPENDED_EXPORTING_SNAPSHOT SUSPENDED_EXPORTING_SNAPSHOT}
     * upon {@linkplain Job#exportSnapshot exporting snapshot}, all of which
     * are reported as user-initiated. Other transitions, such as from {@link
     * JobStatus#NOT_RUNNING NOT_RUNNING} to {@link JobStatus#STARTING
     * STARTING} or from {@link JobStatus#STARTING STARTING} to {@link
     * JobStatus#RUNNING RUNNING}, are not reported as user-initiated.
     * <li> This listener is not notified for {@link JobStatus#COMPLETING
     * COMPLETING} status and observes that the status is transitioned from
     * {@link JobStatus#RUNNING RUNNING} to {@link JobStatus#FAILED FAILED}
     * upon job {@linkplain Job#cancel termination}.
     * <li> This listener is automatically deregistered after a {@linkplain
     * JobStatus#isTerminal terminal event}. </ol>
     *
     * @param event Holds information about the previous and new job statuses,
     *              reason for the status change, and whether it is user-initiated.
     */
    void jobStatusChanged(JobStatusEvent event);
}
